<!DOCTYPE html>
<html lang="en">
<head>
    <meta charset="utf-8">
    <title>Node</title>
    <link rel="stylesheet" href="http://yui.yahooapis.com/3.4.0pr3/build/cssgrids/grids-min.css">
    <link rel="stylesheet" href="../assets/css/main.css">
    <link rel="stylesheet" href="../assets/vendor/prettify/prettify-min.css">
    <script src="../../build/yui/yui-min.js"></script>
</head>
<body>

<div id="doc">
    <h1>Node</h1>

    
        <a href="#toc" class="jump">Jump to Table of Contents</a>
    

    <div class="yui3-g">
        <div id="main" class="yui3-u">
            <div class="content">      <div class="intro">
                                  <p>The Node Utility provides an expressive way to collect, create,  and manipulate DOM nodes.  Each <code>Node</code> instance represents an underlying DOM node, and each <code>NodeList</code> represents a collection of DOM nodes. With <code>Node</code>, you can manage classNames (<code>myNode.addClass(&#x27;foo&#x27;)</code>) and styles (<code>myNode.setStyle(&#x27;opacity&#x27;, 0.5)</code>), create elements (<code>Y.Node.create(&#x27;&lt;div id=&quot;foo&quot; class=&quot;foo&quot;&gt;&lt;p&gt;foo&lt;&#x2F;p&gt;&lt;&#x2F;div&gt;&#x27;)</code>), and much more.</p>
                                  <p><strong>Note: </strong><em>The method <code>Y.get</code> has been deprecated in favor of <code>Y.one</code>.  The methods <code>Node::query</code> and <code>Node::queryAll</code> have been deprecated in favor of <code>Node::one</code> and <code>Node::all</code>  To continue using the deprecated methods, you will need to <code>use(&#x27;node-deprecated&#x27;)</code>. </em></p>

</div>
<h2 id="getting-started">Getting Started</h2>

<p>
To include the source files for Node and its dependencies, first load
the YUI seed file if you haven't already loaded it.
</p>

<pre class="code prettyprint">&lt;script src=&quot;http:&#x2F;&#x2F;yui.yahooapis.com&#x2F;3.4.0&#x2F;build&#x2F;yui&#x2F;yui-min.js&quot;&gt;&lt;&#x2F;script&gt;</pre>


<p>
Next, create a new YUI instance for your application and populate it with the
modules you need by specifying them as arguments to the <code>YUI().use()</code> method.
YUI will automatically load any dependencies required by the modules you
specify.
</p>

<pre class="code prettyprint">&#x2F;&#x2F; Create a new YUI instance and populate it with the required modules.
YUI().use(&#x27;node&#x27;, function (Y) {
    &#x2F;&#x2F; Node is available and ready for use. Add implementation
    &#x2F;&#x2F; code here.
});</pre>


<p>
For more information on creating YUI instances and on the
<a href="http://yuilibrary.com/yui/docs/api/classes/YUI.html#method_use"><code>use()</code> method</a>, see the
documentation for the <a href="../yui/index.html">YUI Global object</a>.
</p>

<div>
				<h2 id="node-using">Using Node</h2>

				<h3 id="using-node">Getting a Node</h3>
				<p>
					 <code>Node</code> is the interface for DOM operations in YUI 3.
					The Node API is based on the standard DOM API, and provides additional sugar
					properties and methods that make common operations easier, and implementation 
					code more concise.  Developers familiar with the standard DOM API will find Node 
					instances to be very familiar.								
				</p>
				<p>
					The simplest way to get a <code>Node</code> instance is using your YUI instance's <code>one</code> method.
                    <code>Y.one</code> accepts either an existing DOM element or a selector query.  If a selector query is used, 
					the first matching element is used.
				</p>
				<p><strong>Note:</strong> CSS3 selector support is not included by default with Node, you will need to include the "selector-css3" module for CSS3 support.</p> 
				<p>
                                This example demonstrates two ways to get a node instance.
				</p>
<pre class="code prettyprint">var node1 = Y.one(&#x27;#main&#x27;);
var node2 = Y.one(document.body);</pre>


				<h3 id="node-properties">Accessing Node Properties</h3>

                                <p>Properties of the underlying DOM node are accessed via the <code>Y.Node</code> instance's <code>set</code> and <code>get</code> methods.  For simple property types (strings, numbers, booleans), these pass directly to/from the underlying node, but properties that normally return DOM nodes return <code>Y.Node</code> instances instead.</p>

				<p>
                                This is an example of getting and setting various properties.
				</p>
<pre class="code prettyprint">var node = Y.one(&#x27;#foo&#x27;);
var parent = node.get(&#x27;parentNode&#x27;); &#x2F;&#x2F; Node instance

var html = &#x27;I am &quot;&#x27; + node.get(&#x27;id&#x27;) + &#x27;&quot;.&#x27;;
html += &#x27;My parent is &quot;&#x27; + parent.get(&#x27;id&#x27;) + &#x27;&quot;&#x27;;

node.set(&#x27;innerHTML&#x27;, html);</pre>

				<h3 id="node-events">DOM Events</h3>

					<p>Use the <code>on</code> method to add an event listener to a <code>Node</code> instance.  
					The event object passed as the first argument to each listener is an event facade 
					that, like the Node API, normalizes browser differences and provides a standard API for 
					working with DOM events based on the W3C standard.  All properties of the event object 
					that would normally return DOM elements return <code>Y.Node</code> instances.
					</p>

<pre class="code prettyprint">Y.one(&#x27;#demo&#x27;).on(&#x27;click&#x27;, function(e) {
    e.preventDefault();
    alert(&#x27;event: &#x27; + e.type + &#x27; target: &#x27; + e.target.get(&#x27;tagName&#x27;)); 
});</pre>



				<h3 id="node-methods">DOM Methods</h3>
                                <p>The <code>Y.Node</code> API provides all of the DOM methods you would expect, plus a few extras to help with common tasks.
                                As with properties and events, any methods that would normally return DOM nodes instead return <code>Y.Node</code> instances.</p>
<pre class="code prettyprint">var node = Y.one(&#x27;#demo&#x27;);
var node2 = node.appendChild(Y.one(&#x27;#foo p&#x27;));
node2.addClass(&#x27;bar&#x27;);</pre>


				<h3 id="nodelist">Using NodeList</h3>
                                <p>The <code>Y.NodeList</code> provides a node-like interface for manipulating multiple nodes through a single interface. The <code>NodeList</code> API is a pared-down version of the <code>Node</code> API, allowing for batching of common tasks.</p>
                                <p>The <code>Y.all</code> method is the simplest way to get a <code>NodeList</code>.</p>
<pre class="code prettyprint">Y.all(&#x27;#demo li&#x27;).addClass(&#x27;bar&#x27;);</pre>

                                <p>The <code>Y.Node</code> api returns <code>NodeList</code> instances when the DOM would normally return a collection of elements.</p>
<pre class="code prettyprint">Y.one(&#x27;#demo&#x27;).get(&#x27;children&#x27;).addClass(&#x27;bar&#x27;);</pre>


				<h3 id="node-query">Node Queries</h3>
                                <p>Selector queries are a powerful way to test and manipulate nodes.  All <code>Y.Node</code> instances support <code>one</code>, <code>all</code>, and <code>test</code>.</p>
<pre class="code prettyprint">var node = Y.one(&#x27;#demo&#x27;);

var node2 = node.one(&#x27;p&#x27;);
if (node2) { &#x2F;&#x2F; might be null
    node2.addClass(&#x27;bar&#x27;); &#x2F;&#x2F; adds &quot;bar&quot; to the first paragraph descendant of #demo
}

node.all(&#x27;p&#x27;).addClass(&#x27;bar&#x27;); &#x2F;&#x2F; adds &quot;bar&quot; to all paragraph descendants of #demo

if (node.test(&#x27;.foo.bar&#x27;)) { &#x2F;&#x2F; &quot;if node has both foo and bar classNames&quot;
    node.removeClass(&#x27;bar&#x27;);
}</pre>


				<p>For more information on selector queries, see the following W3C specifications:</p> 
				<ul>
					<li><a href="http://www.w3.org/TR/css3-selectors/">CSS Level 3 Selectors</a></li>
					<li><a href="http://www.w3.org/TR/selectors-API/">Selectors API</a></li>
				</ul>
				<p><strong>Note:</strong> CSS3 selector support is not included by default with Node, you will need to include the "selector-css3" module for CSS3 support.</p> 


				<h2 id="node-aria">ARIA Support</h2>

				<p>
					The Node interface has support for 
					<a href="http://www.w3.org/TR/wai-aria/">ARIA</a>. 
					When used with Node's built-in support for CSS selector 
					queries, it is easy to both apply and manage a Node's 
					<a href="http://www.w3.org/TR/wai-aria/#roles">roles</a>, 
					<a href="http://www.w3.org/TR/wai-aria/#supportedState">states and properties</a>.
				<p>
				<p>
					The ARIA Roles, States and Properties enhance 
					the semantics of HTML, allowing developers to more 
					accurately describe the intended purpose of a region of a 
					page, or a DHTML widget, thereby improving the user 
					experience for users of assistive technology, such as 
					screen readers.
				</p>
				<p>
					Apply any of the ARIA Roles, States and Properties via 
					the <code>set</code> method.  For example, to apply the 
					role of 
					<a href="http://www.w3.org/TR/wai-aria/#toolbar"><code>toolbar</code></a>
					to a <code>&amp;#60;div&amp;#62;</code> with an id of "toolbar":
				</p>
<pre class="code prettyprint">var node = Y.one(&#x27;#toolbar&#x27;).set(&#x27;role&#x27;, &#x27;toolbar&#x27;);</pre>

				<p>
					Node's built-in support for CSS selector queries, 
					method chaining, and ability to set multiple attributes 
					on a single Node instance makes it especially easy to apply 
					the ARIA Roles, States, and Properties when building 
					DHTML widgets with a large subtree.  For example, when 
					building a menubar widget it is necessary to apply a role 
					of 
					<a href="http://www.w3.org/TR/wai-aria/#menubar"><code>menubar</code></a> 
					to the root DOM element representing the menubar, and the 
					role of 
					<a href="http://www.w3.org/TR/wai-aria/#menu"><code>menu</code></a> 
					to the root DOM element representing each submenu.  
					Additionally, as each submenu is hidden by 
					default, the <a href="http://www.w3.org/TR/wai-aria/#aria-"><code>aria-hidden</code></a> 
					state will need to be applied to each submenu as well.  
					The Node interface makes it possible to do all of this in 
					one line of code:
				</p>
<pre class="code prettyprint">var node = Y.one(&#x27;#rootmenu&#x27;).set(&#x27;role&#x27;, &#x27;menubar&#x27;),
    nodes = node.all(&#x27;.menu&#x27;);
    
nodes.setAttrs({ role: &#x27;menu&#x27;, &#x27;aria-hidden&#x27;: true });</pre>


            <h2 id="node-migration">Migration Table</h2>
            <p>The following table is included to help users migrating from YUI 2.  Most of the functionality from <code>YAHOO.util.Dom</code> is available via <code>Node</code>.</p>
            <p><strong>Note</strong> In the snippets below, <code>myNode</code> is an instance of <code>Node</code>.  Methods that normally would return DOM nodes now return Node instances.</p>
            <table class="yui-table">
                <thead>
                    <tr>
                        <th>2.x <code>(via YAHOO.util.Dom)</code></th>
                        <th>3.0</th>
                    </tr>
                </thead>
                <tbody>
                    <tr>
                        <td>addClass</td>
                        <td>myNode.addClass</td>
                    </tr>
                    <tr>
                        <td>batch</td>
                        <td>NodeList[methodName], NodeList.each, or Y.each</td>
                    </tr>
                    <tr>
                        <td>generateId</td>
                        <td>Y.guid</td>
                    </tr>
                    <tr>
                        <td>get</td>
                        <td>Y.one <strong>Note</strong> strings are now treated as selectors (e.g. "Y.one('#foo')" vs. "YAHOO.util.Dom.get('foo')")</td>
                    </tr>
                    <tr>
                        <td>getAncestorBy</td>
                        <td>myNode.ancestor</td>
                    </tr>
                    <tr>
                        <td>getAncestorByClassName</td>
                        <td>myNode.ancestor</td>
                    </tr>
                    <tr>
                        <td>getAncestorByTagName</td>
                        <td>myNode.ancestor</td>
                    </tr>
                    <tr>
                        <td>getChildren</td>
                        <td>myNode.get('children')</td>
                    </tr>
                    <tr>
                        <td>getChildrenBy</td>
                        <td>myNode.all</td>
                    </tr>
                    <tr>
                        <td>getClientRegion</td>
                        <td>myNode.get('viewportRegion')</td>
                    </tr>
                    <tr>
                        <td>getDocumentHeight</td>
                        <td>myNode.get('docHeight')</td>
                    </tr>
                    <tr>
                        <td>getDocumentScrollLeft</td>
                        <td>myNode.get('docScrollX')</td>
                    </tr>
                    <tr>
                        <td>getDocumentScrollTop</td>
                        <td>myNode.get('docScrollY')</td>
                    </tr>
                    <tr>
                        <td>getDocumentWidth</td>
                        <td>myNode.get('docWidth')</td>
                    </tr>
                    <tr>
                        <td>getElementsBy</td>
                        <td>myNode.all</td>
                    </tr>
                    <tr>
                        <td>getElementsByClassName</td>
                        <td>myNode.all</td>
                    </tr>
                    <tr>
                        <td>getFirstChild</td>
                        <td>myNode.one</td>
                    </tr>
                    <tr>
                        <td>getFirstChildBy</td>
                        <td>myNode.one</td>
                    </tr>
                    <tr>
                        <td>getLastChild</td>
                        <td>myNode.one</td>
                    </tr>
                    <tr>
                        <td>getLastChildBy</td>
                        <td>myNode.one</td>
                    </tr>
                    <tr>
                        <td>getNextSibling</td>
                        <td>myNode.next</td>
                    </tr>
                    <tr>
                        <td>getNextSiblingBy</td>
                        <td>myNode.next</td>
                    </tr>
                    <tr>
                        <td>getPreviousSibling</td>
                        <td>myNode.previous</td>
                    </tr>
                    <tr>
                        <td>getPreviousSiblingBy</td>
                        <td>myNode.previous</td>
                    </tr>
                    <tr>
                        <td>getRegion</td>
                        <td>myNode.get('region')</td>
                    </tr>
                    <tr>
                        <td>getStyle</td>
                        <td>myNode.getStyle</td>
                    </tr>
                    <tr>
                        <td>getViewportHeight</td>
                        <td>myNode.get('winHeight')</td>
                    </tr>
                    <tr>
                        <td>getViewportWidth</td>
                        <td>myNode.get('winWidth')</td>
                    </tr>
                    <tr>
                        <td>getX</td>
                        <td>myNode.getXY</td>
                    </tr>
                    <tr>
                        <td>getY</td>
                        <td>myNode.getXY</td>
                    </tr>
                    <tr>
                        <td>getXY</td>
                        <td>myNode.getXY</td>
                    </tr>
                    <tr>
                        <td>hasClass</td>
                        <td>myNode.hasClass</td>
                    </tr>
                    <tr>
                        <td>inDocument</td>
                        <td>myNode.inDoc</td>
                    </tr>
                    <tr>
                        <td>insertAfter</td>
                        <td>myNode.insert</td>
                    </tr>
                    <tr>
                        <td>insertBefore</td>
                        <td>myNode.insert</td>
                    </tr>
                    <tr>
                        <td>isAncestor</td>
                        <td>myNode.contains (<strong>Note</strong> myNode.contains(myNode) === true)</td>
                    </tr>
                    <tr>
                        <td>removeClass</td>
                        <td>myNode.removeClass</td>
                    </tr>
                    <tr>
                        <td>replaceClass</td>
                        <td>myNode.replaceClass</td>
                    </tr>
                    <tr>
                        <td>setStyle</td>
                        <td>myNode.setStyle</td>
                    </tr>
                    <tr>
                        <td>setX</td>
                        <td>myNode.setXY</td>
                    </tr>
                    <tr>
                        <td>setY</td>
                        <td>myNode.setXY</td>
                    </tr>
                    <tr>
                        <td>setXY</td>
                        <td>myNode.setXY</td>
                    </tr>
                </tbody>
            </table>

		</div>




</div>
        </div>

        <div id="sidebar" class="yui3-u">
            
                <div id="toc" class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Table of Contents</h2>
                    </div>

                    <div class="bd">
                        <ul class="toc">
<li>
<a href="#getting-started">Getting Started</a>
</li>
<li>
<a href="#node-using">Using Node</a>
<ul class="toc">
<li>
<a href="#using-node">Getting a Node</a>
</li>
<li>
<a href="#node-properties">Accessing Node Properties</a>
</li>
<li>
<a href="#node-events">DOM Events</a>
</li>
<li>
<a href="#node-methods">DOM Methods</a>
</li>
<li>
<a href="#nodelist">Using NodeList</a>
</li>
<li>
<a href="#node-query">Node Queries</a>
</li>
</ul>
</li>
<li>
<a href="#node-aria">ARIA Support</a>
</li>
<li>
<a href="#node-migration">Migration Table</a>
</li>
</ul>
                    </div>
                </div>
            

            
                <div class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Examples</h2>
                    </div>

                    <div class="bd">
                        <ul class="examples">
                            
                                
                                    <li data-description="Using selectors and property accessors with Node.">
                                        <a href="properties.html">Set and Get Properties</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Using DOM methods with Node.">
                                        <a href="dom-node.html">DOM Methods</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Listening for DOM events with Node instances.">
                                        <a href="events.html">Handling DOM Events</a>
                                    </li>
                                
                            
                                
                                    <li data-description="NodeList provides Node functionality for multiple nodes.">
                                        <a href="nodelist.html">NodeList</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Using a single event listener to handle events on multiple nodes.">
                                        <a href="node-evt-delegation.html">Delegating Node Events</a>
                                    </li>
                                
                            
                                
                                    <li data-description="This example demonstrates how to position an element in page coordinates.">
                                        <a href="node-xy.html">Node Positioning</a>
                                    </li>
                                
                            
                                
                                    <li data-description="This example demonstrates how to set styles and get style information.">
                                        <a href="node-style.html">Node Styling</a>
                                    </li>
                                
                            
                                
                                    <li data-description="This example demonstrates how to insert content into a Node.">
                                        <a href="node-insert.html">Adding Node Content</a>
                                    </li>
                                
                            
                                
                                    <li data-description="This example demonstrates how to show and hide a Node.">
                                        <a href="node-view.html">Showing and Hiding</a>
                                    </li>
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                        </ul>
                    </div>
                </div>
            

            
                <div class="sidebox">
                    <div class="hd">
                        <h2 class="no-toc">Examples That Use This Component</h2>
                    </div>

                    <div class="bd">
                        <ul class="examples">
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                            
                                
                                    <li data-description="Use the Event Utility to attach simple DOM event handlers.">
                                        <a href="../event/basic-example.html">Simple DOM Events</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Creating an accessible toolbar using the Focus Manager Node Plugin and Node&#x27;s support for the WAI-ARIA Roles and States.">
                                        <a href="../node-focusmanager/node-focusmanager-1.html">Accessible Toolbar</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Creating an accessible menu button using the Focus Manager Node Plugin, Event&#x27;s delegation support and mouseenter event, along with the Overlay widget and Node&#x27;s support for the WAI-ARIA Roles and States.">
                                        <a href="../node-focusmanager/node-focusmanager-3.html">Accessible Menu Button</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Use IO to request XML data from a remote web service.">
                                        <a href="../io/weather.html">Request XML data from Yahoo! Weather</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Use IO to make a cross-domain request to Yahoo! Pipes, returning data from disparate sources.">
                                        <a href="../io/xdr.html">Request JSON using Yahoo! Pipes</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Example Photo Browser application.">
                                        <a href="../dd/photo-browser.html">Photo Browser</a>
                                    </li>
                                
                            
                                
                                    <li data-description="Portal style example using Drag &amp; Drop Event Bubbling and Animation.">
                                        <a href="../dd/portal-drag.html">Portal Style Example</a>
                                    </li>
                                
                            
                        </ul>
                    </div>
                </div>
            
        </div>
    </div>
</div>

<script src="../assets/vendor/prettify/prettify-min.js"></script>
<script>prettyPrint();</script>

</body>
</html>
